@yume-chan/event

@yume-chan/event

Provides a strongly-typed EventEmitter/Event implementation.

Inspired by TypeScript, Visual Studio Code, and more.

• Disposable
• AutoDisposable
• DisposableList
• EventEmitter/Event

Disposable

interface Disposable {
    dispose(): void;
}

Represents anything that need cleanup before the garbage collector recycle it.

AutoDisposable

class AutoDisposable implements Disposable {
    private disposables;
    constructor();
    protected addDisposable<T extends Disposable>(disposable: T): T;
    dispose(): void;
}

A base class for objects that need to manage multiple Disposables.

Calling dispose on it will automatically dispose all Disposables added via addDisposable.

Usually works like:

class MyObject extends AutoDisposable {
    private event1 = this.addDisposable(new EventEmitter<void>());

    private event2 = this.addDisposable(new EventEmitter<void>());

    public dispose() {
        // If the derived class has its own dispose logic
        // Don't forget to call super's `dispose`
        super.dispose();

        // Clean up itself.
    }
}

DisposableList

class DisposableList extends AutoDisposable {
    add<T extends Disposable>(disposable: T): T;
}

An AutoDisposable that can be used alone (i.e. not as a base class).

EventEmitter/Event

interface EventListener<TEvent, TThis, TArgs extends unknown[], TResult> {
    (this: TThis, e: TEvent, ...args: TArgs): TResult;
}

interface RemoveEventListener extends Disposable {
    (): void;
}

interface Event<TEvent, TResult = unknown> {
    (listener: EventListener<TEvent, unknown, [], TResult>): RemoveEventListener;
    <TThis, TArgs extends unknown[]>(listener: EventListener<TEvent, TThis, TArgs, TResult>, thisArg: TThis, ...args: TArgs): RemoveEventListener;
}

class EventEmitter<TEvent, TResult = unknown> implements Disposable {
    protected readonly listeners: EventListenerInfo<TEvent, TResult>[];
    constructor();
    protected addEventListener(info: EventListenerInfo<TEvent, TResult>): RemoveEventListener;
    event: Event<TEvent, TResult>;
    fire(e: TEvent): void;
    dispose(): void;
}

	Node.js EventEmitter	This EventEmitter
Can emit multiple event types	Yes	No
Only trusted source can emit events	No	Yes
Strongly-typed	No	Yes

One EventEmitter for one event type. So for classes that have multiple event types, multiple EventEmitter can be created and assigned to multiple fields.

Usually classes keep EventEmitters private (using TypeScript's private modifier, or ECMAScript private field), only expose the Event interface (via EventEmitter.event).

Everyone can subscribe to the event using the Event interface, but the event can only be emitted from the EventEmitter class.

const emitter = new EventEmitter<void>();
const subscribe = emitter.event;
const unsubscribe = subscribe(() => {});
emitter.fire();
unsubscribe();

The returned unsubscribe is both a function and a Disposable, so it can be used with AutoDisposable or DisposableList.